\chapter{TOUGH2 data files}
\label{datafiles}
\index{TOUGH2 data files}

\section{Introduction}
The \texttt{t2data} library in PyTOUGH contains classes and routines for creating, editing and saving TOUGH2 or AUTOUGH2 data files.  It can be imported using the command:

\begin{lstlisting}
   from t2data import *
\end{lstlisting}

\section{\texttt{t2data} objects}
\index{PyTOUGH!classes!\texttt{t2data}}
\index{TOUGH2 data files!creating}
\index{TOUGH2 data files!objects}

The \texttt{t2data} library defines a \texttt{t2data} class, used for representing TOUGH2 data files.

\textbf{Example:}

\begin{lstlisting}
dat = t2data()
\end{lstlisting}

creates an empty \texttt{t2data} object called \texttt{dat}.

\begin{lstlisting}
dat = t2data(filename)
\end{lstlisting}

creates a \texttt{t2data} object called \texttt{dat} and reads its contents from file \texttt{filename}.  (It is also possible to read the mesh part of the \texttt{t2data} object from separate files - see below.)

Because a \texttt{t2data} object contains a large number of different parameters, it is usually easier to load one from an existing TOUGH2 data file and edit it, rather than creating a new one from scratch. 

\subsection{Properties}

The main properties of a \texttt{t2data} object are listed in Table \ref{tb:t2data_properties}.  In general, each of these properties corresponds to an input block in a TOUGH2 data file.  Most of these input blocks contain a number of different parameters, so that the \texttt{t2data} property corresponding to each input block is usually in the form of a dictionary, containing a number of keys representing sub-properties.

For example, the maximum number of time steps for the simulation is controlled by \texttt{max\_timesteps} key in the \texttt{parameter} property, which for a \texttt{t2data} object called \texttt{dat} would be accessed by \texttt{dat.parameter['max\_timesteps']}.

The details of all the \texttt{t2data} properties are given below.

\index{TOUGH2 data files!properties}
\begin{sidewaystable}
  \begin{center}
    \begin{tabular}{|l|l|l|l|}
      \hline
      \textbf{Property} & \textbf{Type} & \textbf{Description} & \textbf{Input block}\\
      \hline
      \hyperref[sec:t2data:capillarity]{\texttt{capillarity}} & dictionary & capillarity function & RELP\\
      \hyperref[sec:t2data:diffusion]{\texttt{diffusion}} & list & diffusion coefficients & DIFFU\\
      \hyperref[sec:t2data:echo_extra_precision]{\texttt{echo\_extra\_precision}} & Boolean & echoing extra precision sections to main data file (AUTOUGH2 only) & --\\
      \hyperref[sec:t2data:end_keyword]{\texttt{end\_keyword}} & string & keyword to end file & ENDCY or ENDFI\\
      \hyperref[sec:t2data:extra_precision]{\texttt{extra\_precision}} & list & data sections read from extra precision auxiliary file (AUTOUGH2 only) & --\\
      \hyperref[sec:t2data:filename]{\texttt{filename}} & string & file name on disk & --\\
      \hyperref[sec:t2data:generator]{\texttt{generator}} & dictionary & generators (by block name and generator name) & GENER\\
      \hyperref[sec:t2data:generatorlist]{\texttt{generatorlist}} & list & generators (by index) & GENER\\
      \hyperref[sec:t2data:grid]{\texttt{grid}} & \hyperref[t2grids]{\texttt{t2grid}} & model grid & ELEME, CONNE\\
      \hyperref[sec:t2data:history_block]{\texttt{history\_block}} & list & history blocks (TOUGH2 only) & FOFT\\
      \hyperref[sec:t2data:history_connection]{\texttt{history\_connection}} & list & history connections (TOUGH2 only) & COFT\\
      \hyperref[sec:t2data:history_generator]{\texttt{history\_generator}} & list & history generators (TOUGH2 only) & GOFT\\
      \hyperref[sec:t2data:incon]{\texttt{incon}} & dictionary & initial conditions & INCON\\
      \hyperref[sec:t2data:indom]{\texttt{indom}} & dictionary & rocktype-specific initial conditions & INDOM\\
      \hyperref[sec:t2data:lineq]{\texttt{lineq}} & dictionary & linear equation solver options (AUTOUGH2 only) & LINEQ\\
      \hyperref[sec:t2data:meshfilename]{\texttt{meshfilename}} & string or tuple & file name(s) on disk containing mesh data & --\\
      \hyperref[sec:t2data:meshmaker]{\texttt{meshmaker}} & list & mesh generation options & MESHM\\
      \hyperref[sec:t2data:more_options]{\texttt{more\_option}} & array of integer & additional parameter options & MOMOP\\
      \hyperref[sec:t2data:multi]{\texttt{multi}} & dictionary & EOS configuration & MULTI\\
      \hyperref[sec:t2data:noversion]{\texttt{noversion}} & Boolean & suppressing printing of version summary & NOVER\\
      \hyperref[sec:t2data:num_generators]{\texttt{num\_generators}} & integer & number of generators & --\\
      \hyperref[sec:t2data:output_times]{\texttt{output\_times}} & dictionary & times to write output & TIMES\\
      \hyperref[sec:t2data:parameter]{\texttt{parameter}} & dictionary & run-time parameters & PARAM\\
      \hyperref[sec:t2data:relative_permeability]{\texttt{relative\_permeability}} & dictionary & relative permeability function & RELP\\
      \hyperref[sec:t2data:selection]{\texttt{selection}} & dictionary & selection parameters & SELEC\\
      \hyperref[sec:t2data:short_output]{\texttt{short\_output}} & dictionary & short output (AUTOUGH2 only) & SHORT\\
      \hyperref[sec:t2data:simulator]{\texttt{simulator}} & string & simulator name (AUTOUGH2 only) & SIMUL\\
      \hyperref[sec:t2data:solver]{\texttt{solver}} & dictionary & linear equation solver options (TOUGH2 only) & SOLVR\\
      \hyperref[sec:t2data:start]{\texttt{start}} & Boolean & run initialisation option & START\\
      \hyperref[sec:t2data:title]{\texttt{title}} & string & simulation title & TITLE\\
      \hyperref[sec:t2data:type]{\texttt{type}} & string & simulator type (AUTOUGH2 or TOUGH2) & --\\
      \hline
    \end{tabular}
    \caption{Properties of a \texttt{t2data} object}
    \label{tb:t2data_properties}
  \end{center}
\end{sidewaystable}

\begin{snugshade}
\subsubsection{\texttt{capillarity} property}
\end{snugshade}
\label{sec:t2data:capillarity}
\index{TOUGH2 data files!capillarity}

A dictionary property specifying the capillarity function used, corresponding to the second line of the \textbf{RPCAP} input block in the TOUGH2 data file.  The individual keys of this property are given in Table \ref{tb:capillarity}.

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|l|l|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \texttt{parameters} & array (7) of float & function parameters & CP\\
      \texttt{type} & integer & type of capillarity function & ICP\\
      \hline
    \end{tabular}
    \caption{\texttt{capillarity} property keys}
    \label{tb:capillarity}
  \end{center}
\end{table}

\begin{snugshade}
\subsubsection{\texttt{diffusion} property}
\end{snugshade}
\label{sec:t2data:diffusion}
\index{TOUGH2 data files!diffusion}

A list property specifying diffusion coefficients for each mass component simulated, corresponding to the \textbf{DIFFU} input block in the TOUGH2 data file.  The list has length \texttt{multi['num\_components']} (i.e. NK in TOUGH2 terminology), and each element is a list of the diffusion coefficients for each component (with length \texttt{multi['num\_phases']}, or NPH).

\begin{snugshade}
\subsubsection{\texttt{echo\_extra\_precision} property}
\end{snugshade}
\label{sec:t2data:echo_extra_precision}
\index{TOUGH2 data files!extra precision}
\index{TOUGH2!AUTOUGH2}

A Boolean property (AUTOUGH2 only) governing whether data written to an auxiliary extra-precision file is also echoed to the main data file.  If \texttt{True}, all extra-precision data sections are echoed to the main file.

\begin{snugshade}
\subsubsection{\texttt{end\_keyword} property}
\end{snugshade}
\label{sec:t2data:end_keyword}
\index{TOUGH2 data files!end keyword}

A string property containing the keyword used in the data file to end the file.  Normally this is `ENDCY', but `ENDFI' can also be used.

\begin{snugshade}
\subsubsection{\texttt{extra\_precision} property}
\end{snugshade}
\label{sec:t2data:extra_precision}
\index{TOUGH2 data files!extra precision}
\index{TOUGH2!AUTOUGH2}

A list property determining which data sections will be written to an auxiliary extra-precision file (AUTOUGH2 only).  Recent versions of AUTOUGH2 support an additional data file containing some data written with extra precision.  Possible extra-precision data sections are ROCKS, ELEME, CONNE, RPCAP and GENER.  Typical usage of this extra-precision data is for automatic model calibration using PEST or similar software, where calculation of derivatives of model outputs with respect to model parameters requires higher precision than is possible with the standard TOUGH2 data file format.

The \texttt{extra\_precision} parameter may be a list containing names of sections to be written in extra precision (e.g. [`RPCAP', `GENER']), or set to \texttt{False} to disable extra precision (equivalent to []), or to \texttt{True} to specify that all possible sections should be written in extra precision.

The \hyperref[sec:t2data:read]{\texttt{read()}} method of a \texttt{t2data} object determines whether extra precision data are available by searching for an additional file with the same base name as the data file itself, but with a '.pdat' or '.PDAT' extension (depending on the case of the main data file name).  If no such file exists, then no extra precision data will be read.

\begin{snugshade}
\subsubsection{\texttt{filename} property}
\end{snugshade}
\label{sec:t2data:filename}
\index{TOUGH2 data files!filename}

A string property containing the name of the TOUGH2 data file on disk.  (This does not correspond to any parameter in the TOUGH2 data file.)

\begin{snugshade}
\subsubsection{\texttt{generator} property}
\end{snugshade}
\label{sec:t2data:generator}
\index{TOUGH2 data files!generators}

A dictionary property containing the generators for the simulation, accessed by tuples of block name and generator name.  Each generator is an object of type \hyperref[t2generatorobjects]{\texttt{t2generator}}, which is described in section \ref{t2generatorobjects}.

\begin{snugshade}
\subsubsection{\texttt{generatorlist} property}
\end{snugshade}
\label{sec:t2data:generatorlist}
\index{TOUGH2 data files!generators}

A list property containing the generators for the simulation, accessed by index.

\begin{snugshade}
\subsubsection{\texttt{grid} property}
\end{snugshade}
\label{sec:t2data:grid}
\index{TOUGH2 data files!grid}

A \hyperref[t2grids]{\texttt{t2grid}} object (see chapter \ref{t2grids}) representing the simulation grid, corresponding to the \textbf{ELEME} and \textbf{CONNE} input blocks in a TOUGH2 data file.

\begin{snugshade}
\subsubsection{\texttt{history\_block} property}
\end{snugshade}
\label{sec:t2data:history_block}
\index{TOUGH2 data files!history blocks}
\index{TOUGH2 data files!FOFT}

A list property containing blocks for which time history output is required, corresponding to the \textbf{FOFT} input block in a TOUGH2 data file.  If the \texttt{t2data} object contains grid data, the items in this list are \hyperref[t2blockobjects]{\texttt{t2block}} objects; otherwise, they are block names (i.e. strings).

\begin{snugshade}
\subsubsection{\texttt{history\_connection} property}
\end{snugshade}
\label{sec:t2data:history_connection}
\index{TOUGH2 data files!history connections}
\index{TOUGH2 data files!COFT}

A list property containing connections for which time history output is required, corresponding to the \textbf{COFT} input block in a TOUGH2 data file.  If the \texttt{t2data} object contains grid data, the items in this list are \hyperref[t2connectionobjects]{\texttt{t2connection}} objects; otherwise, they are tuples of block names (i.e. tuples of strings).

\begin{snugshade}
\subsubsection{\texttt{history\_generator} property}
\end{snugshade}
\label{sec:t2data:history_generator}
\index{TOUGH2 data files!history generators}
\index{TOUGH2 data files!GOFT}

A list property containing blocks in which generators are defined and for which time history output is required, corresponding to the \textbf{GOFT} input block in a TOUGH2 data file.  If the \texttt{t2data} object contains grid data, the items in this list are \hyperref[t2blockobjects]{\texttt{t2block}} objects; otherwise, they are block names (i.e. strings).

\begin{snugshade}
\subsubsection{\texttt{incon} property}
\end{snugshade}
\label{sec:t2data:incon}
\index{TOUGH2 data files!initial conditions}
\index{TOUGH2 initial conditions!in data file}

A dictionary property representing the initial conditions for the simulation, accessed by block name, corresponding to the \textbf{INCON} input block in a TOUGH2 data file.  The value of each element of the dictionary is a list consisting of the porosity of the block, followed by a list of the specified initial primary thermodynamic variables in the block. If the TOUGH2 NSEQ and NADD values are used, these are stored after the thermodynamic variables. If they are not used, they can either be set to \texttt{None} or simply omitted.

For example, to specify porosity 0.1 and initial conditions (101.3E3, 20.0) in block \texttt{'AB105'} of a \texttt{t2data} object called \texttt{dat}, set \texttt{dat.incon['AB105'] = [0.1, [101.3e3, 20.0]]}.

To specify these same conditions but with NSEQ = 10 and NADD = 2, set \texttt{dat.incon['AB105'] = [0.1, [101.3e3, 20.0], 10, 2]}.

Porosity can be specified as \texttt{None} if default porosity (from the rocktype) is to be used.

\begin{snugshade}
\subsubsection{\texttt{indom} property}
\end{snugshade}
\label{sec:t2data:indom}
\index{TOUGH2 data files!initial conditions!by rocktype}

A dictionary property representing the initial conditions for the simulation, accessed by rocktype name, corresponding to the \textbf{INDOM} input block in a TOUGH2 data file.  The value of each element of the dictionary is a list consisting of the specified initial primary thermodynamic variables for the rocktype.

\begin{snugshade}
\subsubsection{\texttt{lineq} property}
\end{snugshade}
\label{sec:t2data:lineq}
\index{TOUGH2 data files!linear equation solver!AUTOUGH2}
\index{TOUGH2!AUTOUGH2}

A dictionary property representing linear equation solver options, corresponding to the \textbf{LINEQ} input block in an AUTOUGH2 data file.  The individual keys of this property are given in Table \ref{tb:lineq}.

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|l|l|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{AUTOUGH2 parameter}\\
      \hline
      \texttt{epsilon} & float & solver tolerance & EPN\\
      \texttt{gauss} & integer & Gauss elimination parameter & IGAUSS\\
      \texttt{max\_iterations} & integer & max. number of iterations & MAXIT\\
      \texttt{num\_orthog} & integer & number of orthogonalisations & NORTH\\
      \texttt{type} & integer & type of solver (1 or 2) & ISOLVR\\
      \hline
    \end{tabular}
    \caption{\texttt{lineq} property keys}
    \label{tb:lineq}
  \end{center}
\end{table}

\begin{snugshade}
\subsubsection{\texttt{meshfilename} property}
\end{snugshade}
\label{sec:t2data:meshfilename}
\index{TOUGH2 data files!mesh file}

A string property (or tuple of strings) containing the name(s) of files on disk containing the mesh data.  (This does not correspond to any parameter in the TOUGH2 data file.)  Its default value is an empty string which means mesh data will be read from the main data file.

If \texttt{meshfilename} is a single (non-empty) string, this is interpreted as the name of a formatted text file containing `ELEME' and `CONNE' sections specifying the mesh (e.g. the `MESH' file created by TOUGH2 or TOUGH2\_MP).

If \texttt{meshfilename} is a tuple of two strings, these are interpreted as the names of two binary files containing the mesh data, e.g. the `MESHA' and `MESHB' files created by TOUGH2\_MP.

\begin{snugshade}
\subsubsection{\texttt{meshmaker} property}
\end{snugshade}
\label{sec:t2data:meshmaker}
\index{TOUGH2 data files!mesh maker}

A list property representing mesh generation options, corresponding to the \textbf{MESHM} input block in a TOUGH2 data file.  For more detail on the use of \textbf{MESHM} data, consult the TOUGH2 users' guide \citep{tough2}.

The \textbf{MESHM} data may contain multiple sections (e.g. creation of a rectilinear XYZ grid followed by MINC processing), so the \texttt{meshmaker} property is structured as a list of two-element tuples, each containing the type of section (\texttt{rz2d}, \texttt{xyz} or \texttt{minc}) followed by the section data itself.

The form of the section data varies depending on the section type.  For the \texttt{rz2d} type it is also structured as a list, as these types may contain variable numbers of sub-sections.  (For example, data for the \texttt{rz2d} type may contain multiple \texttt{logar} sub-sections for different logarithmic radial parts of the mesh.)  Each sub-section is again a two-element tuple, consisting of the sub-section type (a string) followed by a dictionary containing the data for the sub-section.

Data for the \texttt{xyz} type are also structured as a list, with the first element containing the stand-alone \texttt{deg} parameter (a float), followed by the other sub-sections, corresponding to the \textbf{NX}, \textbf{NY} and \textbf{NZ} sub-sections in the TOUGH2 data file.  The \texttt{minc} type does not have sub-sections so MINC data are not structured as a list but simply a dictionary.

Possible sub-section types for \texttt{rz2d} data are \texttt{radii}, \texttt{equid}, \texttt{logar} and \texttt{layer}, corresponding to their (uppercase) keyword counterparts in the TOUGH2 data file.  Data keys for these types are given in Table \ref{tb:rz2d}.  Data keys for the \texttt{xyz} and \texttt{minc} data are given in Tables \ref{tb:xyz} and \ref{tb:minc}.

\textbf{Example}: The easiest way to understand how the \texttt{meshmaker} property works is to read some example input data into a \texttt{t2data} object and examine the result.  The \textbf{MESHM} data for the standard TOUGH2 test problem `rhbc' (`Production from a geothermal reservoir with hypersaline brine') is represented as a \texttt{t2data} \texttt{meshmaker} property as follows:

\begin{lstlisting}
[('rz2d',[
 ('radii', {'radii': [5.0]}),
 ('equid', {'dr': 2.0, 'nequ': 1}),
 ('logar', {'rlog': 100.0, 'nlog': 50}),
 ('logar', {'rlog': 1000.0, 'nlog': 20}),
 ('equid', {'dr': 0.0, 'nequ': 1}),
 ('layer', {'layer': [500.0]})
 ])
]
\end{lstlisting}

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|l|l|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \multicolumn{4}{|c|}{\textbf{radii} sub-section keys}\\
      \hline
      \texttt{radii} & list & specified mesh radii & RC\\
      \hline
      \multicolumn{4}{|c|}{\textbf{equid} sub-section keys}\\
      \hline
      \texttt{dr} & float & radial increment & DR\\
      \texttt{nequ} & integer & number of equidistant radii & NEQU\\
      \hline
      \multicolumn{4}{|c|}{\textbf{logar} sub-section keys}\\
      \hline
      \texttt{dr} & float & reference radial increment & DR\\
      \texttt{nlog} & integer & number of logarithmic radii & NLOG\\
      \texttt{rlog} & float & largest radius & RLOG\\
      \hline
      \multicolumn{4}{|c|}{\textbf{layer} sub-section keys}\\
      \hline
      \texttt{layer} & list & layer thicknesses & H\\
      \hline
    \end{tabular}
    \caption{\texttt{rz2d} data keys}
    \label{tb:rz2d}
  \end{center}
\end{table}

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|l|l|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \multicolumn{4}{|c|}{\texttt{deg} parameter}\\
      \hline
      \texttt{deg} & float & angle between y-axis and horizontal & DEG\\
      \hline
      \multicolumn{4}{|c|}{NX, NY and NZ keys}\\
      \hline
      \texttt{del} & float & constant grid increment & DEL\\
      \texttt{deli} & list & variable grid increments & DEL\\
      \texttt{no} & integer & number of grid increments & DR\\
      \texttt{ntype} & string & axis direction (`NX', `NY' or `NZ') & NTYPE\\
      \hline
    \end{tabular}
    \caption{\texttt{xyz} data keys}
    \label{tb:xyz}
  \end{center}
\end{table}

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|l|l|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \texttt{dual} & string & treatment of global matrix-matrix flow & DUAL\\
      \texttt{num\_continua} & integer & number of interacting continua & J\\
      \texttt{spacing} & list & fracture spacings & PAR\\
      \texttt{type} & string & proximity function type & TYPE\\
      \texttt{vol} & list & volume fractions & VOL\\
      \texttt{where} & string & direction of volume fraction specification & WHERE\\
      \hline
    \end{tabular}
    \caption{\texttt{minc} data keys}
    \label{tb:minc}
  \end{center}
\end{table}

\begin{snugshade}
\subsubsection{\texttt{more\_option} property}
\end{snugshade}
\label{sec:t2data:more_options}
\index{TOUGH2 data files!simulation parameters}

An array property containing additional integer parameter options, corresponding to the \textbf{MOMOP} input block in a TOUGH2 data file (it is not recognised by AUTOUGH2). Introduced by iTOUGH2, this is an extension of the \texttt{parameter.option} property. It is of length 21 and is populated with zeros by default. Like the \texttt{parameter.option} property, values are accessed using 1-based (not zero-based) indices.

\begin{snugshade}
\subsubsection{\texttt{multi} property}
\end{snugshade}
\label{sec:t2data:multi}
\index{TOUGH2 data files!equation of state}

A dictionary property selecting the equation of state (EOS) module used and setting associated parameters, corresponding to the \textbf{MULTI} input block in a TOUGH2 or AUTOUGH2 data file.  The individual keys of this property are given in Table \ref{tb:multi}.

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|p{37mm}|p{23mm}|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \texttt{eos} & string & EOS name (AUTOUGH2 only) & NAMEOS\\
      \texttt{num\_components} & integer & number of components & NK\\
      \texttt{num\_equations} & integer & number of equations & NEQ\\
      \texttt{num\_inc} & integer & number of mass components in INCON data (TOUGH2 only) & NKIN\\
      \texttt{num\_phases} & integer & number of phases & NPH\\
      \texttt{num\_secondary\_parameters} & integer & number of secondary parameters & NB\\
      \hline
    \end{tabular}
    \caption{\texttt{multi} property keys}
    \label{tb:multi}
  \end{center}
\end{table}

\begin{snugshade}
\subsubsection{\texttt{noversion} property}
\end{snugshade}
\label{sec:t2data:noversion}

A Boolean property specifying whether to suppress printing of version and date information, corresponding to the \textbf{NOVER} input block in a TOUGH2 data file.

\begin{snugshade}
\subsubsection{\texttt{num\_generators} property}
\end{snugshade}
\label{sec:t2data:num_generators}
\index{TOUGH2 data files!generators!number of}

A read-only integer property returning the number of generators.

\begin{snugshade}
\subsubsection{\texttt{output\_times} property}
\end{snugshade}
\label{sec:t2data:output_times}
\index{TOUGH2 data files!output times}

A dictionary property specifying the times at which model output is required, corresponding to the \textbf{TIMES} input block in a TOUGH2 data file.  The individual keys of this property are given in Table \ref{tb:outputtimes}.

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|l|p{20mm}|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \texttt{max\_timestep} & float & maximum time step & DELAF\\
      \texttt{num\_times\_specified} & integer & number of times specified & ITI\\
      \texttt{num\_times} & integer & total number of times & ITE\\
      \texttt{time} & list of float & times at which output is required & TIS\\
      \texttt{time\_increment} & float & time increment after specified times & TINTER\\
      \hline
    \end{tabular}
    \caption{\texttt{output\_times} property keys}
    \label{tb:outputtimes}
  \end{center}
\end{table}

\begin{snugshade}
\subsubsection{\texttt{parameter} property}
\end{snugshade}
\label{sec:t2data:parameter}
\index{TOUGH2 data files!simulation parameters}

A dictionary property specifying run-time parameters, corresponding to the \textbf{PARAM} input block in a TOUGH2 data file.  The individual keys of this property are given in Table \ref{tb:parameter}.

The \texttt{option} parameter (MOP array in TOUGH2) is an array of 24 integers, and has a 1-based index so that its indices are the same as those in the TOUGH2 documentation.  (In fact it is really zero-based, like all other Python arrays, but has an extra unused zero$^{th}$ element).

\begin{sidewaystable}
  \begin{center}
    \begin{tabular}{|l|l|l|l|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \texttt{absolute\_error} & float & absolute convergence tolerance & RE2\\
      \texttt{be} & float & enhanced vapour diffusion & BE\\
      \texttt{const\_timestep} & float & time step length & DELTEN\\
      \texttt{default\_incons} & list of float & default initial conditions & DEP\\
      \texttt{derivative\_increment} & float & numerical derivate increment factor & DFAC\\
      \texttt{diff0} & float & diffusive vapour flux (AUTOUGH2 only) & DIFF0\\
      \texttt{gravity} & float & gravitational acceleration & GF\\
      \texttt{max\_duration} & integer & maximum simulation duration (machine seconds) & MSEC\\
      \texttt{max\_iterations} & integer & maximum number of iterations per time step & NOITE\\
      \texttt{max\_timesteps} & integer & maximum number of time steps & MCYC\\
      \texttt{max\_timestep} & float & maximum time step size & DELTMX\\
      \texttt{newton\_weight} & float & Newton-Raphson weighting factor & WNR\\
      \texttt{option} & array(24) of integer & simulation options & MOP\\
      \texttt{pivot} & float & pivoting parameter for linear solver & U\\
      \texttt{print\_block} & string & block name for short printout & ELST\\
      \texttt{print\_interval} & integer & time step interval for printing & MCYPR\\
      \texttt{print\_level} & integer & amount of printout & KDATA\\
      \texttt{relative\_error} & float & relative convergence tolerance & RE1\\
      \texttt{scale} & float & grid scale factor & SCALE\\
      \texttt{texp} & float & binary diffusion temperature parameter & TEXP\\
      \texttt{timestep\_reduction} & float & time step reduction factor & REDLT\\
      \texttt{timestep} & list of float & specified time step sizes & DLT\\
      \texttt{tstart} & float & start time (seconds) & TSTART\\
      \texttt{tstop} & float & stop time & TIMAX\\
      \texttt{upstream\_weight} & float & upstream weighting factor & WUP\\
      \hline
    \end{tabular}
    \caption{\texttt{parameter} property keys}
    \label{tb:parameter}
  \end{center}
\end{sidewaystable}

\begin{snugshade}
\subsubsection{\texttt{relative\_permeability} property}
\end{snugshade}
\label{sec:t2data:relative_permeability}
\index{TOUGH2 data files!relative permeability}

A dictionary property specifying the relative permeability function used, corresponding to the first line of the \textbf{RPCAP} input block in the TOUGH2 data file.  The individual keys of this property are given in Table \ref{tb:relativepermeability}.

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|l|p{20mm}|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \texttt{parameters} & array (7) of float & function parameters & RP\\
      \texttt{type} & integer & type of relative permeability function & IRP\\
      \hline
    \end{tabular}
    \caption{\texttt{relative\_permeability} property keys}
    \label{tb:relativepermeability}
  \end{center}
\end{table}

\begin{snugshade}
\subsubsection{\texttt{selection} property}
\end{snugshade}
\label{sec:t2data:selection}
\index{TOUGH2 data files!selection parameters}

A dictionary property representing selection parameters for the simulation (only used by some EOS modules, e.g. EOS7, EOS7R, EWASG), corresponding to the \textbf{SELEC} block in the TOUGH2 data file.

The dictionary contains two keys: `integer' and `float', the first of which accesses a list of the integer selection parameters (the first line of the \textbf{SELEC} block), while the second accesses a list of the float selection parameters (the remaining lines of the \textbf{SELEC} block).

\begin{snugshade}
\subsubsection{\texttt{short\_output} property}
\end{snugshade}
\label{sec:t2data:short_output}
\index{TOUGH2 data files!short output}
\index{TOUGH2!AUTOUGH2}

A dictionary property representing blocks, connections and generators for which short output is required, corresponding to the \textbf{SHORT} input block in an AUTOUGH2 data file.

The dictionary contains four keys: `frequency', `block', `connection' and `generator'. The last three of these access lists of blocks, connections and generators respectively for short output.  (Note that each of these lists contains \hyperref[t2blockobjects]{\texttt{t2block}}, \hyperref[t2connectionobjects]{\texttt{t2connection}} or \hyperref[t2generatorobjects]{\texttt{t2generator}} objects, rather than names.)  The `frequency' key accesses the time step frequency (an integer) for which short output is required.

\begin{snugshade}
\subsubsection{\texttt{simulator} property}
\end{snugshade}
\label{sec:t2data:simulator}
\index{TOUGH2 data files!simulator type}

A string property specifying the type of simulator, corresponding to the \textbf{SIMUL} input block in an AUTOUGH2 data file.

\begin{snugshade}
\subsubsection{\texttt{solver} property}
\end{snugshade}
\label{sec:t2data:solver}
\index{TOUGH2 data files!linear equation solver!TOUGH2}

A dictionary property representing linear equation solver options, corresponding to the \textbf{SOLVR} input block in a TOUGH2 data file.  The individual keys of this property are given in Table \ref{tb:solver}.

\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|l|l|}
      \hline
      \textbf{Key} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \texttt{closure} & float & convergence criterion & CLOSUR\\
      \texttt{relative\_max\_iterations} & float & relative max. number of iterations & RITMAX\\
      \texttt{type} & integer & solver type & MATSLV\\
      \texttt{o\_precond} & string & O-preconditioning type & OPROCS\\
      \texttt{z\_precond} & string & Z-preconditioning type & ZPROCS\\
      \hline
    \end{tabular}
    \caption{\texttt{solver} property keys}
    \label{tb:solver}
  \end{center}
\end{table}

\begin{snugshade}
\subsubsection{\texttt{start} property}
\end{snugshade}
\label{sec:t2data:start}
\index{TOUGH2 data files!flexible start option}

A Boolean property specifying whether the flexible start option is used, corresponding to the \textbf{START} input block in a TOUGH2 data file.

\begin{snugshade}
\subsubsection{\texttt{title} property}
\end{snugshade}
\label{sec:t2data:title}
\index{TOUGH2 data files!title}

A string property containing the simulation title, corresponding to the \textbf{TITLE} input block in a TOUGH2 data file.

\begin{snugshade}
\subsubsection{\texttt{type} property}
\end{snugshade}
\label{sec:t2data:type}
\index{TOUGH2 data files!simulator type}
\index{TOUGH2}
\index{TOUGH2!AUTOUGH2}

A string property specifying the simulator type (`AUTOUGH2' or `TOUGH2').  Changing the value of this property will cause one of the \hyperref[sec:t2data:convert_to_TOUGH2]{\texttt{convert\_to\_TOUGH2()}} or \hyperref[sec:t2data:convert_to_AUTOUGH2]{\texttt{convert\_to\_AUTOUGH2()}} methods to be executed, with default method parameters.  Hence, changing the \texttt{type} property to `AUTOUGH2' causes the EOS to be set to the default `EW'.  It is also not possible to specify TOUGH2\_MP options when setting \texttt{type}.  For more control over how the conversion is carried out, use the conversion methods directly instead of setting \texttt{type}.

\subsection{Functions for reading data from file}
\index{TOUGH2 data files!reading}

It is possible to specify customized functions to control how data are read from a TOUGH2 data file. This is done using the optional \texttt{read\_function} parameter when a \texttt{t2data} object is created- in exactly the same way it is done for a \texttt{mulgrid} object. For more details, see the corresponding documentation for \texttt{mulgrid} objects in section \ref{mulgridreadfunctions}. By default, the read functions for \texttt{t2data} objects are given by the \texttt{default\_read\_function} dictionary.

\subsection{Methods}

The main methods of a \texttt{t2data} object are listed in Table \ref{tb:t2data_methods}.  Details of these methods are given below.

\index{TOUGH2 data files!methods}
\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|p{65mm}|}
      \hline
      \textbf{Method} & \textbf{Type} & \textbf{Description}\\
      \hline
      \hyperref[sec:t2data:add_generator]{\texttt{add\_generator}} & -- & adds a generator\\
      \hyperref[sec:t2data:clear_generators]{\texttt{clear\_generators}} & -- & deletes all generators\\
      \hyperref[sec:t2data:convert_to_AUTOUGH2]{\texttt{convert\_to\_AUTOUGH2}} & -- & converts from TOUGH2 input to AUTOUGH2\\
      \hyperref[sec:t2data:convert_to_TOUGH2]{\texttt{convert\_to\_TOUGH2}} & -- & converts from AUTOUGH2 input to TOUGH2\\
      \hyperref[sec:t2data:delete_generator]{\texttt{delete\_generator}} & -- & deletes a generator\\
      \hyperref[sec:t2data:delete_orphan_generators]{\texttt{delete\_orphan\_generators}} & -- & deletes orphaned generators\\
      \hyperref[sec:t2data:effective_incons]{\texttt{effective\_incons}} & list or \hyperref[incons]{\texttt{t2incon}} & effective initial conditions\\
      \hyperref[sec:t2data:generator_index]{\texttt{generator\_index}} & integer & returns index of generator with specified name and block name\\
      \hyperref[sec:t2data:json]{\texttt{json}} & dictionary & Waiwera JSON input \\
      \hyperref[sec:t2data:read]{\texttt{read}} & \hyperref[datafiles]{\texttt{t2data}} & reads data file from disk\\
      \hyperref[sec:t2data:rename_blocks]{\texttt{rename\_blocks}} & -- & renames blocks\\
      \hyperref[sec:t2data:run]{\texttt{run}} & -- & runs a TOUGH2 simulation\\
      \hyperref[sec:t2data:specific_generation]{\texttt{specific\_generation}} & \texttt{np.array} & generation per unit volume in each block\\
      \hyperref[sec:t2data:total_generation]{\texttt{total\_generation}} & \texttt{np.array} & total generation in each block\\
      \hyperref[sec:t2data:transfer_from]{\texttt{transfer\_from}} & -- & transfers data from another \texttt{t2data} object\\
      \hyperref[sec:t2data:write]{\texttt{write}} & -- & writes to data file on disk\\
      \hline
    \end{tabular}
    \caption{Methods of a \texttt{t2data} object}
    \label{tb:t2data_methods}
  \end{center}
\end{table}

\begin{snugshade}
\subsubsection{\texttt{add\_generator(\emph{generator})}}
\end{snugshade}
\label{sec:t2data:add_generator}
\index{TOUGH2 data files!adding!generators}
\index{TOUGH2 data files!generators!adding}

Adds a generator to the data file object.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{generator}: \hyperref[t2generatorobjects]{\texttt{t2generator}}\\
  Generator to be added to the data file object.
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{convert\_to\_AUTOUGH2(\emph{warn}=True, \emph{MP}=False, \emph{simulator}='AUTOUGH2.2',\
    \emph{eos}='EW')}}
\end{snugshade}
\label{sec:t2data:convert_to_AUTOUGH2}
\index{TOUGH2 data files!converting!to AUTOUGH2}
\index{TOUGH2 data files!simulator type}
\index{TOUGH2!AUTOUGH2}
\index{TOUGH2}

Converts a TOUGH2 (or TOUGH2\_MP) data file for use with AUTOUGH2.  Various parameter options are altered to try to make the AUTOUGH2 simulation give similar results to the original TOUGH2 simulation.  If necessary, the \texttt{filename} property is changed to end in `.dat' (or `.DAT', depending on the case of the base file name), as required by AUTOUGH2.

The simulator and EOS name can also be specified, as AUTOUGH2 data files contain this information in the SIMUL and MULTI sections.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{warn}: Boolean\\
  If \texttt{True}, warnings will be printed regarding TOUGH2 options used in the original data file which are not supported in AUTOUGH2.
\item \textbf{MP}: Boolean\\
  if \texttt{True}, treats the original \texttt{t2data} object as a TOUGH2\_MP data file, which uses some of the parameters differently (e.g. MOP(20)).
\item \textbf{simulator}: string\\
  Simulator name, used for the leading part of the AUTOUGH2 SIMUL data section.  Possible values are `MULKOM', `TOUGH2', `TOUGH2.2', `AUTOUGH2' and `AUTOUGH2.2'.
\item \textbf{eos}: string\\
  EOS name, used for the trailing part of the AUTOUGH2 SIMUL data section (e.g. `EW', `EWC', `EWA', `EWAV' etc.)
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{convert\_to\_TOUGH2(\emph{warn}=True, \emph{MP}=False)}}
\end{snugshade}
\label{sec:t2data:convert_to_TOUGH2}
\index{TOUGH2 data files!converting!to TOUGH2}
\index{TOUGH2 data files!simulator type}
\index{TOUGH2!AUTOUGH2}
\index{TOUGH2}

Converts an AUTOUGH2 data file for use with TOUGH2 (or compatible simulators such as TOUGH2\_MP).  Various parameter options are altered to try to make the TOUGH2 simulation give similar results to the original AUTOUGH2 simulation.  This particularly affects AUTOUGH2 options related to backward compatibility with MULKOM.  In particular, if these are used then the heat conductivities in the ROCKS block have to be altered to give the same results.  Data blocks specific to AUTOUGH2 (e.g. SIMULATOR, LINEQ, and SHORT) are removed, and AUTOUGH2-specific generator types are converted to their TOUGH2 equivalents if possible, or otherwise deleted.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{warn}: Boolean\\
  If \texttt{True}, warnings will be printed regarding AUTOUGH2 options used in the original data file which are not supported in TOUGH2.
\item \textbf{MP}: Boolean\\
  if \texttt{True}, converts to a TOUGH2\_MP data file, which treats some of the parameters differently (e.g. MOP(20)).  The \texttt{filename} property is also changed to INFILE, as required by TOUGH2\_MP. 
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{clear\_generators()}}
\end{snugshade}
\label{sec:t2data:clear_generators}
\index{TOUGH2 data files!generators!deleting}
\index{TOUGH2 data files!deleting!generators}

Deletes all generators from the data file object.

\begin{snugshade}
\subsubsection{\texttt{delete\_generator(\emph{blocksourcenames})}}
\end{snugshade}
\label{sec:t2data:delete_generator}
\index{TOUGH2 data files!generators!deleting}
\index{TOUGH2 data files!deleting!generators}

Deletes the generator with the specified block and generator (source) name, if it exists.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{blocksourcenames}: tuple\\
  Tuple of block name and generator name (both strings) of the generator to be deleted.
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{delete\_orphan\_generators()}}
\end{snugshade}
\label{sec:t2data:delete_orphan_generators}
\index{TOUGH2 data files!generators!deleting}
\index{TOUGH2 data files!deleting!generators}

Deletes all generators with block names that are not in the grid.

\begin{snugshade}
\subsubsection{\texttt{effective\_incons(\emph{incons} = \texttt{None})}}
\end{snugshade}
\label{sec:t2data:effective_incons}
\index{TOUGH2 data files!initial conditions}

Returns effective initial conditions, based on on the specified initial conditions in combination
with any initial conditions specified in the \texttt{t2data} object itself -- whether as
default initial conditions specified via the
\hyperref[sec:t2data:parameter]{\texttt{parameter}} property,
or via the \hyperref[sec:t2data:incon]{\texttt{incon}} property, or the
\hyperref[sec:t2data:indom]{\texttt{indom}} property (or any combination of these).

Any \texttt{indom} specifications override the defaults in the \texttt{parameter} property.
Values in the \texttt{incon} property override both the defaults and values in \texttt{indom}.
Finally, values passed into this method via the \texttt{incons} parameter override any other
specifications. Note that any of these may contain incomplete specifications (i.e. values
are not specified for all blocks in the grid).

If only default homogeneous initial conditions are in effect, then a list of the primary variables
is returned. Otherwise, a \hyperref[incons]{\texttt{t2incon}} object is returned with initial
conditions values for every block.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{incons}: \texttt{t2incon} or \texttt{None}\\
  Initial conditions object, usually representing the contents of a separate initial conditions file.
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{generator\_index(\emph{blocksourcenames})}}
\end{snugshade}
\label{sec:t2data:generator_index}
\index{TOUGH2 data files!generators!indices of}

Returns the index (in the \texttt{generatorlist} list) of the generator with the specified block and generator name.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{blocksourcenames}: tuple\\
  Tuple of block name and generator name (both strings) of the generator.
\end{itemize}

\begin{snugshade}
  \subsubsection{\texttt{json(\emph{geo}, \emph{mesh\_filename}, \emph{atmos\_volume} = 1.e25,
      \emph{incons} = \texttt{None}, \emph{eos} = \texttt{None}, \\
      \emph{bdy\_incons} = \texttt{None}, \emph{mesh\_coords} = 'xyz')}}
\end{snugshade}
\label{sec:t2data:json}
\index{TOUGH2 data files!JSON}

Returns a JSON dictionary representing the contents of the \texttt{t2data} object (and associated
mesh geometry), suitable for input to the Waiwera simulator (\url{http://waiwera.github.io}).

\textbf{Parameters:}
\begin{itemize}
\item \textbf{geo}: \hyperref[mulgrids]{\texttt{mulgrid}}\\
  Geometry object. Note that geometric meshes with column surface elevations that do not correspond to layer elevations are not supported in Waiwera. For meshes of this type, the column surface elevations can be ``snapped'' to layer elevations using the \hyperref[sec:mulgrid:snap_columns_to_nearest_layers]{\texttt{snap\_columns\_to\_nearest\_layers()}} method. In that case the \texttt{t2grid} in the \texttt{t2data} object must be updated so it corresponds to the snapped mesh geometry, and other parts of the data file updated to reference the new mesh (e.g. using the \hyperref[sec:t2data:transfer_from]{\texttt{transfer\_from()}} method). The geometry's \hyperref[sec:mulgrid:blockordering]{\texttt{block\_order}} property should be set to `dmplex', particularly if it contains mixtures of 3- and 4-sided columns.
\item \textbf{mesh\_filename}: string\\
  The filename of the mesh file (e.g. ExodusII or GMSH mesh) for the Waiwera simulation.
\item \textbf{atmos\_volume}: float\\
  Maximum block volume for blocks to be considered part of the geometric grid. Blocks with volume greater than this value (or zero) will be treated as boundary condition (e.g. atmosphere) blocks rather than part of the simulation mesh.
\item \textbf{incons}: \hyperref[incons]{\texttt{t2incon}}, string, or \texttt{None}\\
  Initial conditions for the Waiwera model. If specified as a string, this should be the filename of the Waiwera HDF5 output file for restarting the simulation from the output of a previous run. If \texttt{None} is specified, then default initial conditions will be applied from the \texttt{parameter} property (see \ref{sec:t2data:parameter}).  
\item \textbf{eos}: string, integer or \texttt{None}\\
  Equation of state used for the simulation. For AUTOUGH2 simulations, this can generally be set to \texttt{None}, and the EOS will be read from the \texttt{t2data} \texttt{simulator} or \texttt{multi} properties. Otherwise, it can be specified as an integer corresponding to the EOS number (1 being pure water, 2 being water / CO$_2$ etc.) or as a string corresponding to the AUTOUGH2 EOS names (EOS1 being `EW', EOS2 being `EWC' etc.). Note that only EOS modules 1, 2 and 4 (i.e. `W', `EW', `EWC' and `EWAV' in terms of AUTOUGH2 EOS names) are supported.
\item \textbf{bdy\_incons}: \hyperref[incons]{\texttt{t2incon}}, or \texttt{None}\\
  TOUGH2 initial conditions from which boundary conditions are to be derived. In many cases this parameter is not needed, because boundary conditions are taken from the \texttt{incons} parameter: if the \texttt{incons} parameter is specified as a \texttt{t2incon} object, then the \texttt{bdy\_incons} parameter can be set to \texttt{None}. If, however, \texttt{incons} is a string or \texttt{None}, then it will not contain boundary condition data, in which case boundary conditions can be specified by passing a \texttt{t2incon} object as the \texttt{bdy\_incons} parameter; otherwise, if this is set to \texttt{None} then default boundary conditions will be applied from the default initial conditions in the \texttt{t2data} \texttt{parameter} property. Faces on which to apply boundary conditions are identified by the presence of connections to blocks with either zero or large volume (above the volume specified by the \texttt{atmos\_volume} parameter). Note that for side boundary conditions (with horizontal connections), the boundary blocks must have centres defined, otherwise it is not possible to calculate the appropriate normal vector for the boundary condition.
\item \textbf{mesh\_coords}: string\\
  String representing the coordinate system to be used in the Waiwera model. 3-D Cartesian meshes are identified as `xyz'. 2-D Cartesian meshes may be identified as either `xy', `xz', or `yz' (depending on orientation), while 2-D radial meshes are identified as `rz'.
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{read(\emph{filename}, \emph{meshfilename}='')}}
\end{snugshade}
\label{sec:t2data:read}
\index{TOUGH2 data files!reading}

Reads a \texttt{t2data} object from a TOUGH2 data file on disk.  The mesh data may optionally be read from auxiliary files, if it is not present in the main data file.  (Note that if the main data file does contain mesh information (the `ELEME' and `CONNE' sections), any auxiliary mesh files will not be read.)

\textbf{Parameters:}
\begin{itemize}
\item \textbf{filename}: string\\
  Name of the TOUGH2 data file to be read.
\item \textbf{meshfilename}: string or tuple\\
  Name of separate mesh file(s) to read, containing element and connection data.  If empty, then mesh data will be read from the main data file.  If a non-empty string is given, this is interpreted as the name of a formatted text file containing `ELEME' and `CONNE' data sections (as in the `MESH' files created by TOUGH2 and TOUGH2\_MP). If a tuple of two filenames is given, these are interpreted as the names of the two binary MESHA and MESHB files used by TOUGH2\_MP.
\end{itemize}

Note that it is possible to create a \texttt{t2data} object and read its contents in from disk files in one step, e.g.: \texttt{dat = t2data(filename,meshfilename)}.

\begin{snugshade}
\subsubsection{\texttt{rename\_blocks(\emph{blockmap}=\{\}, \emph{invert}=False, \emph{fix\_blocknames} = True)}}
\end{snugshade}
\label{sec:t2data:rename_blocks}
\index{TOUGH2 data files!renaming blocks}

Renames blocks in the model according to the specified block mapping dictionary. Any block whose name is a key of the block mapping dictionary is renamed with the corresponding dictionary value. The blocks in the \hyperref[t2grids]{\texttt{t2grid}} object are renamed using its own \hyperref[sec:t2grid:rename_blocks]{\texttt{rename\_blocks()}} method. Other \texttt{t2data} properties such as generators, initial conditions and history specifications are similarly renamed.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{blockmap}: dictionary\\
  Block mapping dictionary, mapping strings to strings.
\item \textbf{invert}: Boolean\\
  Set \texttt{True} to invert the block mapping dictionary, i.e. to map its values to its keys. This can be used, for example, to rename the blocks to correspond to a geometry created using the \hyperref[t2grids]{\texttt{t2grid}} \hyperref[sec:t2grid:rectgeo]{\texttt{rectgeo()}} method, via the block mapping dictionary also created by that method.
\item \textbf{fix\_blocknames}: Boolean\\
  Set \texttt{True} (the default) to `fix' block names in the dictionary, using the \hyperref[sec:mulgrid:fix_blockname]{\texttt{fix\_blockname()}} function. 
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{run(\emph{save\_filename}='', \emph{incon\_filename}='', \emph{simulator}='AUTOUGH2\_2',\\
    \emph{silent}=False, \emph{output\_filename}='')}}
\end{snugshade}
\label{sec:t2data:run}
\index{TOUGH2 data files!running}

Runs an AUTOUGH2 or TOUGH2 (but not TOUGH2\_MP) simulation using the data file corresponding to a \texttt{t2data} object.  The contents of the \texttt{t2data} object must first have been written to disk using the \texttt{write} function.  If the file names for the save file or initial conditions file are not specified, they are constructed by changing the file extension of the data file name.  The name of the TOUGH2 executable can be specified.

\index{TOUGH2}
For running TOUGH2 (rather than AUTOUGH2), the name of the TOUGH2 executable must be specified via the \texttt{simulator} parameter.  However, the \texttt{save\_filename} and \texttt{incon\_filename} parameters do not need to be specified.  Initial conditions will be read from the file INCON and final results written to SAVE.  The listing file name will be the same as the data file name, but with the extension changed to *.listing, unless the \texttt{output\_filename} is specified.

\index{TOUGH2!TOUGH2-MP}
Running TOUGH2\_MP is generally done via MPI rather than directly, and the exact syntax for doing so may vary with different implementations of MPI (OpenMPI, MPICH2 etc.)  It is also necessary to specify the number of processors to use.  However it is still possible to run TOUGH2\_MP from a Python script using a system call, e.g.:

\begin{lstlisting}
from os import system
system("mpirun -np 16 t2eos1_mp")
\end{lstlisting}

\textbf{Parameters:}
\begin{itemize}
\item \textbf{save\_filename}: string\\
  Name of the save file to be written to disk during the simulation (AUTOUGH2 only).  Default is `base.save' where the AUTOUGH2 data file name is `base.dat'.
\item \textbf{incon\_filename}: string\\
  Name of the initial conditions file for the simulation (AUTOUGH2 only).  Default is `base.incon' where the AUTOUGH2 data file name is `base.dat'.
\item \textbf{simulator}: string\\
  Name of the AUTOUGH2 or TOUGH2 executable.  Default is `AUTOUGH2\_2'.
\item \textbf{silent}: Boolean\\
  Set to \texttt{True} to suppress output to the display while running (default is \texttt{False}).
\item \textbf{output\_filename}: string\\
  Name of the output listing file for the simulation (TOUGH2 only).  Default is `base.listing' where the base name of the TOUGH2 data file (without file extension) is `base'.
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{specific\_generation(\emph{type}='MASS', \emph{name}='')}}
\end{snugshade}
\label{sec:t2data:specific_generation}
\index{TOUGH2 data files!generators!specific generation rates}

Returns an \texttt{np.array} containing the total specific generation rate in each block (i.e. generation rate per unit volume) for the specified generator type and name.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{type}: string\\
  Generation type (`HEAT', `MASS' etc.) -- default is `MASS'.
\item \textbf{name}: string\\
  Regular expression to match generator names (e.g. `SP...' (or `\^{}SP') will match all generators with names beginning with `SP'.)
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{transfer\_from(\emph{source}, \emph{sourcegeo}, \emph{geo}, \emph{top\_generator}=[], \emph{bottom\_generator}=[],\\
    \emph{sourceinconfilename}='', \emph{inconfilename}='', \emph{rename\_generators}=False, \\
    \emph{preserve\_generation\_totals}=False)}}
\end{snugshade}
\label{sec:t2data:transfer_from}
\index{TOUGH2 data files!transferring}

Transfers data from another \texttt{t2data} object, and its associated \texttt{mulgrid} object.  Parameters, rock types and rock type assignments, and optionally initial conditions files are transferred.  In general the data for a given block in the geometry is found by identifying the nearest block in the source geometry and transferring data from that block.  There are, however, exceptions, such as for generators that need to remain on the surface or bottom of the model.  The \texttt{top\_generator} and \texttt{bottom\_generator} lists specify the `layer' part of the generator name for generators that should remain on the top or bottom of the model, respectively.

For generator types in which the \texttt{gx} and \texttt{rate} properties represent generation rates (as opposed to other types for which these properties are used to represent other things, e.g. productivity index for wells on deliverability), the values of \texttt{gx} and \texttt{rate} are scaled to account for the different volume of the block the generator has been mapped into.  If \texttt{preserve\_generation\_totals} is \texttt{True}, and a generator with generation rate $G$ is mapped into $n$ blocks with volumes $V_1, V_2,\ldots, V_n$, then the generation rate for the new generator in block $i$ will be $G V_i/\sum_{k=1}^{n}{V_k}$.  This should preserve the total generation rate over the model.  (For generator types matching the \texttt{bottom\_generator} or \texttt{top\_generator} specifications, the column area instead of the block volume is used to determine the appropriate scaling.)  Note that of the columns a top or bottom generator is mapped into, only those with centres inside the source geometry are included in the scaling calculations.  The generator types for which this scaling is carried out are: ` AIR', `COM1', `COM2', `COM3', `COM4', `COM5', `HEAT', `MASS', `NACL', `TRAC'  and ` VOL'.

If both \texttt{sourceinconfilename} and \texttt{inconfilename} are specified, a new initial conditions file with filename \texttt{inconfilename} is written to disk, with initial conditions transferred from the file \texttt{sourceinconfilename}.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{source}: \hyperref[datafiles]{\texttt{t2data}}\\
  The \texttt{t2data} object to transfer data from.
\item \textbf{sourcegeo}: \hyperref[mulgrids]{\texttt{mulgrid}}\\
  The \texttt{mulgrid} object corresponding to \texttt{source}.
\item \textbf{geo}: \hyperref[mulgrids]{\texttt{mulgrid}}\\
  The \texttt{mulgrid} object corresponding to the destination \texttt{t2data} object.
\item \textbf{top\_generator}: list\\
  A list of generator `layer' identifier strings for generators that need to be kept at the top of the model (e.g. rain generators).
\item \textbf{bottom\_generator}: list\\
  A list of generator `layer' identifier strings for generators that need to be kept at the bottom of the model (e.g. basement heat and mass inputs).
\item \textbf{sourceinconfilename}: string\\
  Name of the (optional) initial conditions file to transfer initial conditions data from (corresponding to \texttt{source}).
\item \textbf{inconfilename}: string\\
  Name of the (optional) initial conditions file to write, corresponding to the destination \texttt{t2data} object.
\item \textbf{rename\_generators}: Boolean\\
  If \texttt{False}, generators other than those at the top and bottom of the model retain their original names.  Otherwise, they will be renamed according to their column names in the new grid.
\item \textbf{preserve\_generation\_totals}: Boolean\\
  If \texttt{False} (the default), the transfer of generators will attempt to preserve the distribution of specific generation of the original model; otherwise, it will attempt to preserve the total generation over the model.
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{total\_generation(\emph{type}='MASS', \emph{name}='')}}
\end{snugshade}
\label{sec:t2data:total_generation}
\index{TOUGH2 data files!generators!total generation rates}

Returns an \texttt{np.array} containing the total generation rate in each block for the specified generator type and name.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{type}: string\\
  Generation type (`HEAT', `MASS' etc.) -- default is `MASS'.
\item \textbf{name}: string\\
  Regular expression to match generator names (e.g. `SP...' (or `\^{}SP') will match all generators with names beginning with `SP'.)
\end{itemize}

\begin{snugshade}
\subsubsection{\texttt{write(\emph{filename}='', \emph{meshfilename}='', \emph{extra\_precision}=None,\\
    \emph{echo\_extra\_precision}=None)}}
\end{snugshade}
\label{sec:t2data:write}
\index{TOUGH2 data files!writing}
\index{TOUGH2 data files!mesh file}
\index{TOUGH2 data files!extra precision}

Writes a \texttt{t2data} object to a TOUGH2 data file on disk.  If the \texttt{meshfilename} parameter is used, mesh information can be written to auxiliary mesh files.

\textbf{Parameters:}
\begin{itemize}
\item \textbf{filename}: string\\
  Name of the TOUGH2 data file to be written.  If no file name is specified, the object's own \texttt{filename} property is used.
\item \textbf{meshfilename}: string or tuple\\
  Name of auxiliary mesh file(s) to be written.  If this is empty (the default), the object's own \texttt{meshfilename} property is used.  Otherwise, if a single (non-empty) string is given, this in interpreted as the name of a file to write formatted mesh information to (as in the `MESH' files produced by TOUGH2 and TOUGH2\_MP).  If a tuple of two strings is given, this in interpreted as the names of two binary files (as in the `MESHA' and `MESHB' files produced by TOUGH2\_MP).
\item \textbf{extra\_precision}: list or Boolean\\
  Controls whether to write extra precision data to auxiliary file (AUTOUGH2 only).  If set to \texttt{True}, then all possible sections will be written to the extra precision file.  Currently the possible extra-precision sections are the ROCKS, ELEME, CONNE, RPCAP and GENER sections.  If set to \texttt{False} or [], then no extra-precision data will be written.  If set to a list of section names (e.g. [`RPCAP', `GENER']), then only those sections will be written in extra precision.  If set to \texttt{None} (the default), then the value of the data object's \texttt{extra\_precision} property is used.  Otherwise, the value of this property is overwritten by the value specified here.
\item \textbf{echo\_extra\_precision}: Boolean or None\\
  Controls whether to echo all extra-precision data sections to the main data file (AUTOUGH2 only).  If \texttt{None}, the value of the data object's \texttt{echo\_extra\_precision} property is used.  Otherwise, the value of this property is overwritten by the value specified here.
\end{itemize}

\section{\texttt{t2generator} objects}
\label{t2generatorobjects}
\index{PyTOUGH!classes!\texttt{t2generator}}
\index{TOUGH2 data files!generators}

A \texttt{t2generator} object represents a generator in a TOUGH2 simulation (i.e. an item in the generation table).  The properties of a \texttt{t2generator} object are given in Table \ref{tb:t2generator_properties}.  These correspond closely to the parameters specified in the TOUGH2 \textbf{GENER} input block.  A \texttt{t2generator} object has no methods.

\index{TOUGH2 data files!generators!properties}
\begin{table}
  \begin{center}
    \begin{tabular}{|l|l|p{60mm}|p{20mm}|}
      \hline
      \textbf{Property} & \textbf{Type} & \textbf{Description} & \textbf{TOUGH2 parameter}\\
      \hline
      \texttt{block} & string & name of block containing the generator & EL, NE\\
      \texttt{enthalpy} & list of float & generation enthalpies ($|$ltab$|>$1, itab$<>$`')& F3\\
      \texttt{ex} & float & enthalpy for injection & EX\\
      \texttt{gx} & float & generation rate (or productivity index for deliverability) & GX\\
      \texttt{hg} & float & layer thickness for deliverability & HG\\
      \texttt{fg} & float & separator pressure/ injectivity etc. & FG\\
      \texttt{itab} & string & blank unless table of specific enthalpies specified & ITAB\\
      \texttt{ltab} & integer & number of generation times (or open layers for deliverability) & LTAB\\
      \texttt{nadd} & integer & successive block increment & NADD\\
      \texttt{nads} & integer & successive generator increment & NADS\\
      \texttt{name} & string & generator name & SL, NS\\
      \texttt{nseq} & integer & number of additional generators & NSEQ\\
      \texttt{rate} & list of float & generation rates ($|$ltab$|>$1)& F2\\
      \texttt{time} & list of float & generation times ($|$ltab$|>$1)& F1\\
      \texttt{type} & string & generator type (default `MASS') & TYPE\\
      \hline
    \end{tabular}
    \caption{Properties of a \texttt{t2generator} object}
    \label{tb:t2generator_properties}
  \end{center}
\end{table}

\section{Example}
\index{examples!TOUGH2 data files}

The following piece of Python script opens a MULgraph geometry file and TOUGH2 data file, changes some TOUGH2 run-time parameters and assigns heat generators to the blocks in the bottom layer inside a defined area, with the specified total heat divided uniformly amongst the generators.

\begin{lstlisting}
geo = mulgrid('gmodel.dat')
dat = t2data('model.dat')

dat.parameter['max_timesteps'] = 300
dat.parameter['print_interval'] = dat.parameter['max_timesteps']/10
dat.parameter['option'][16] = 5 # time step control

dat.clear_generators()
totalheat = 10.e6
layer = geo.layerlist[-1]  # bottom layer
cols = [col for col in geo.columnlist if 10.e3 <= col.centre[0] <= 20.e3]
totalarea = sum([col.area for col in cols])
q = totalheat / totalarea

for col in cols:
    blockname = geo.block_name(layer.name, col.name)
    gen = t2generator(name = ' q'+col.name, block = blockname, type = 'HEAT', gx = q*col.area)
    dat.add_generator(gen)

dat.write()

\end{lstlisting}
